# 主题配置

主题配置位于 `doc` 配置中的 `themeConfig` 下。例如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    // ...
  },
});
```

## nav

- **类型**：`Array`
- **默认值**： `[]`

网站的导航栏。 `nav` 配置是 `NavItem` 的数组，具有以下类型：

```ts
interface NavItem {
  // 导航栏文本
  text: string;
  // 导航栏链接
  link: '/';
  // 导航栏链接的激活规则
  activeMatch: '^/$|^/';
  // 图标配置(可选)，填入 svg 标签内容或者图片 URL
  tag?: string;
}
```

`activeMatch` 用于匹配当前路由，当路由匹配 `activeMatch` 规则时，nav 项会高亮显示。默认情况下，`activeMatch` 是 nav 项的 `link`。

比如:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Home',
        link: '/',
      },
      {
        text: 'Guide',
        link: '/guide/',
      },
    ],
  },
});
```

当然 `nav` 数组中也可以配置多级菜单，类型如下:

```ts
interface NavGroup {
  // 导航栏文本
  text: string;
  // 子菜单
  items: NavItem[];
  // 图标配置(可选)，填入 svg 标签内容或者图片 URL
  tag?: string;
}
```

例如下面的配置:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Home',
        link: '/',
      },
      {
        text: 'Guide',
        items: [
          {
            text: 'Getting Started',
            link: '/guide/getting-started',
          },
          {
            text: 'Advanced',
            link: '/guide/advanced',
          },
        ],
      },
    ],
  },
});
```

## sidebar

- **类型**：`Object`

网站的侧边栏。配置为一个对象，类型如下：

```ts
// key 为 SidebarGroup 的路径
// value 为 SidebarGroup 的数组
type Sidebar = Record<string, SidebarGroup[]>;

interface SidebarGroup {
  text: string;
  link?: string;
  items: SidebarItem[];
  // 是否可折叠
  collapsible?: boolean;
  // 是否默认折叠
  collapsed?: boolean;
  // 图标配置(可选)，填入 svg 标签内容或者图片 URL
  tag?: string;
}

// 可填入一个对象，也可以填入一个字符串
// 填入字符串时，内部会转换成一个对象，字符串会被当做 link，text 值会自动取对应文档的标题
type SidebarItem =
  | {
      // 侧边栏文本
      text: string;
      // 侧边栏链接
      link: string;
      // 图标配置(可选)，填入 svg 标签内容或者图片 URL
      tag?: string;
    }
  | string;
```

比如:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            // 填入一个对象
            {
              text: 'Introduction',
              link: '/guide/getting-started/introduction',
            },
            {
              text: 'Installation',
              link: '/guide/getting-started/installation',
            },
          ],
        },
        {
          text: 'Advanced',
          items: [
            // 直接填入链接字符串
            '/guide/advanced/customization',
            '/guide/advanced/markdown',
          ],
        },
      ],
    },
  },
});
```

## footer

- **类型**：`Object`
- **默认值**： `{}`

主页的页脚。

`footer` 配置是 `Footer` 的一个对象，它具有以下类型：

```ts
export interface Footer {
  message?: string;
}
```

`message` 是一个可以包含 HTML 内容的字符串。这个字符串将使用 `dangerouslySetInnerHTML` 插入到页脚中，因此你可以传入 HTML 模板标签来设计你的页脚。

比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    footer: {
      message:
        '<p>这是一个包含<a href="https://example.com">链接</a>的<strong>页脚</strong></p>',
    },
  },
});
```

## socialLinks

- **类型**：`Array`
- **默认值**： `[]`

你可以通过如下的配置添加相关链接，比如 `github` 链接、`x` 链接等。
相关链接支持四种模式：`链接模式link` `文本模式text` `图片模式img` `自定义模式dom`，相关例子如下：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    socialLinks: [
      {
        icon: 'github',
        mode: 'link',
        content: 'https://github.com/sanyuan0704/island.js',
      },
      {
        icon: 'wechat',
        mode: 'text',
        content: '微信号 foo',
      },
      {
        icon: 'qq',
        mode: 'img',
        content: '/qrcode.png',
      },
      {
        icon: 'github',
        mode: 'dom',
        content:
          '<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/rjhwzy/ljhwZthlaukjlkulzlp/rspress/rspress-navbar-logo-0904.png" alt="logo" id="logo" class="mr-4 rspress-logo dark:hidden">',
      },
    ],
  },
});
```

- 当`link`模式时，点击 icon 即可跳转链接。
- 当`text`模式时，鼠标移到 icon 上会显示弹框，弹框内容是输入的文本。
- 当`img`模式时，鼠标移到 icon 上会显示弹框，弹框内容是指定的图片，需要注意的是，图片需要放在`public`目录下。
- 当`dom`模式时，可以直接在 content 字段中传入需要自定义html。使用''进行包裹。

相关链接支持以下几种图片，通过 icon 属性来选择：

```ts
export type SocialLinkIcon =
  | 'lark'
  | 'discord'
  | 'facebook'
  | 'github'
  | 'instagram'
  | 'linkedin'
  | 'slack'
  | 'x'
  | 'youtube'
  | 'wechat'
  | 'qq'
  | 'juejin'
  | 'zhihu'
  | 'bilibili'
  | 'weibo'
  | 'gitlab'
  | 'X'
  | 'bluesky'
  | 'npm'
  | { svg: string };
```

如果需要自定义 icon，可以通过传入一个带有 `svg 属性` 的对象，svg 的值为自定义图标内容即可，比如：

```js
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    socialLinks: [
      {
        icon: {
          svg: '<svg>foo</svg>',
        },
        mode: 'link',
        content: 'https://github.com/',
      },
    ],
  },
});
```

## nextPageText

- **类型**：`string`
- **默认值**： `Next Page`

下一页的文本。比如:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    nextPageText: 'Next Page',
  },
});
```

## locales

- **类型**：`Array<LocaleConfig>`
- **默认值**： `undefined`

国际化配置。此配置为一个数组，数组中的每一项都是一个 `LocaleConfig` 对象，它具有以下类型：

```ts
export interface LocaleConfig {
  /**
   * 通用站点信息，优先级高于 `locales` 中的配置
   */
  // 语言名称
  lang?: string;
  // HTML 标题，优先于 `themeConfig.title`
  title?: string;
  // HTML 描述，优先于 `themeConfig.description`
  description?: string;
  // 对应语言的显示文本
  label: string;
}
```

`LocaleConfig` 中包含许多与主题配置中相同的配置项，但它的优先级会更高。

## darkMode

- **类型**：`boolean`
- **默认值**： `true`

是否出现暗黑模式/白天模式切换按钮。比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    darkMode: true,
  },
});
```

同时，你也可以通过在 HTML 中注入如下的全局变量来指定默认的主题模式：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  builderConfig: {
    html: {
      tags: [
        {
          tag: 'script',
          // 通过 window.RSPRESS_THEME 变量来指定默认的主题模式，可选值为 'dark' 和 'light'
          children: "window.RSPRESS_THEME = 'dark';",
        },
      ],
    },
  },
});
```

## editLink

- Type:

```ts
interface EditLink {
  /**
   * 自定义编辑链接的 URL
   */
  docRepoBaseUrl: string;
}
```

- **默认值**： `undefined`

用于配置编辑链接，以在 GitHub 或 GitLab 等 Git 管理服务上编辑页面。

比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    editLink: {
      docRepoBaseUrl:
        'https://github.com/web-infra-dev/rspress/tree/main/website/docs',
    },
  },
});
```

## enableContentAnimation

- **类型**：`boolean`
- **默认值**： `false`

在页面切换的时候是否显示转场动画，使用 [View Transition API](https://developer.mozilla.org/docs/Web/API/View_Transitions_API) 实现。例如：

> 转场动画暂时不能配置。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    enableContentAnimation: true,
  },
});
```

## enableAppearanceAnimation

- **类型**：`boolean`
- **默认值**： `false`

在浅色和深色主题之间切换时是否有动画效果，使用 [View Transition API](https://developer.mozilla.org/docs/Web/API/View_Transitions_API) 实现。例如：

> 切换动画暂时不能配置。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    enableAppearanceAnimation: true,
  },
});
```

## search

- **类型**：`boolean`
- **默认值**： `true`

是否显示搜索框。比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    search: false,
  },
});
```

## enableScrollToTop

- **类型**：`boolean`
- **默认值**： `false`

启用文档上的滚动到顶部按钮. 比如:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    enableScrollToTop: true,
  },
});
```

## localeRedirect

- **类型**：`'auto' | 'never' | 'only-default-lang'`
- **默认值**： `'auto'`

是否在访问网站时重定向到最接近 `window.navigator.language` 的语言，默认为 `auto` 表示首次访问时将重定向，`never` 表示不重定向，`only-default-lang` 表示仅在访问默认语言时重定向。比如:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    localeRedirect: 'never',
  },
});
```

## fallbackHeadingTitle

- **类型**：`boolean`
- **默认值**： `true`

是否在文档不书写 H1 时将 [`frontmatter.title`](./config-frontmatter#title) 作为后备内容。比如:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    fallbackHeadingTitle: false,
  },
});
```

```mdx
---
title: 文档标题
---

## 正文内容
```
